<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
    <title>Single Class</title>
</head>
<body>
  <h3>Mapping a single class</h3>
  This section provides information on various persistence annotations that are used to map primitive properties of an entity. Persistence annotations can be applied at three levels - <em>class, method</em> and <em>field</em>.
  <ul>
    <li>Class</li>
    Annotations such as <em>@Entity</em> and <em>@Table</em> are applied at the class level.
    <li>Method</li>
    Annotations such as <em>@Id</em> and <em>@Column</em> can be applied at method level. When done so, it implies Property Access mode. It means persistence provider such as Hibernate will use <em>getters</em> and <em>setters</em> to access entity state. Annotations must be placed on the <em>getter</em> methods.
    <li>Field</li>
    Annotations such as <em>@Id</em> and <em>@Column</em> can be applied at field level. When done so, it implies Field Access mode. It means persistence provider such as Hibernate will use fields directly to access entity state.
  </ul>
  Mixed Mode access is also possible, but for obvious reasons it along with the Field Access mode should be used with caution.
  <p>
    Here are a few points to note about the mapping of Person class in the example -
    <ul>
      <li><em>@Entity</em> annotation at the class level marks a pojo such as Person as a persistent entity.</li>
      <li><em>@Table</em> annotation is used to customize the table name to which this persistent entity is mapped. Entity name is used as table name if this annotation is not present.</li>
      <li>Primary key is mapped using <em>@Id</em> annotation. The id generation strategy can be any one of <em>AUTO, TABLE, SEQUENCE,</em> or <em>IDENTITY</em> enumerated values of the <em>GenerationType</em> enumerated type.</li>
      <li><em>@Column</em> annotation maps a property of a persistent entity to a database table column. Various attributes such as <em>nullable, precision, scale</em> and <em>length</em> can be used to define database level constraints. The name of the column can be customized using <em>name</em> attribute. If not specified, name of the column is same as property name.</li>
      <li>The properties of persistent entity that are not mapped to any database column are denoted by <em>@Transient</em> annotation.</li>
      <li>Enumerated properties of an entity are mapped using <em>@Enumerated</em> annotation. There are two ways to persist enumerated constant values in database. Using <em>EnumType.STRING</em> attribute persists the string value while <em>EnumType.ORDINAL</em> persists its position in its enum declaration. For example, the <em>Gender</em> Enum used in the example looks like this -
      <pre class="brush: java">
public enum Gender {
	MALE, FEMALE;
}        
      </pre>
      If we use <em>EnumType.STRING</em>, the value persisted in database column would be MALE or FEMALE and if we use <em>EnumType.ORDINAL</em>, the value would be 0 for MALE and 1 for FEMALE. Care must be taken while using <em>EnumType.ORDINAL</em> as the ordinal value could change if some more constants are added to Enum later.
      </li>
      <li>Date time properties are mapped using <em>@Temporal</em> annotation. You can specify if you would like to use Date, Time or Timestamp using <em>DATE, TIME</em> and <em>TIMESTAMP</em> constants of <em>TemporalType</em> Enum.</li>
    </ul>
    Persistence providers such as Hibernate provide features that go beyond JPA2 standard. The code snippet below demonstrates a couple of them.
    <ol>
      <li>Generated Properties</li>
      There are some properties of persistent entities whose values could be generated at database level, for example, created timestamp of record. Such properties are marked using the Hibernate extension <em>@org.hibernate.annotations.Generated</em> annotation. Whenever Hibernate issues an SQL INSERT or UPDATE for an entity that has defined generated properties, it immediately does a SELECT afterward to retrieve the generated values.Generated properties must be marked as noninsertable and nonupdatable using the standard <em>@Column insertable = false, updatable = false</em> attributes. Also, <em>columnDefinition</em> attribute of <em>@Column</em> annotation can be used to customize the generated DDL. In the example below, we make the <em>createdtimestamp</em> column as a database generated one with CURRENT_TIMESTAMP as it's value.
      <li>Derived Properties</li>
      The value of derived properties is calculated at runtime by evaluating an expression that you define using the formula attribute. The given SQL formula is evaluated every time the entity is retrieved from the database.Formulas may refer to columns of the database table, they can call SQL functions, and they may even include SQL subselects. The SQL expression is passed to the
underlying database as is.
    </ol>
    <pre class="brush: java">
	@org.hibernate.annotations.Generated(
			org.hibernate.annotations.GenerationTime.ALWAYS)
	@Column(insertable = false, updatable = false, 
			columnDefinition = "TIMESTAMP DEFAULT CURRENT_TIMESTAMP")
	public Date getCreatedTimestamp() {
		return createdTimestamp;
	}
	
	@org.hibernate.annotations.Formula(
			value = "IF(gender = 'MALE', 'Mr', 'Ms')")
	public String getTitle() {
		return title;
	}
    </pre>
  </p>
</body>
</html>
